ACM V8 - System Handbook

This handbook is a complete, implementation-level walkthrough of ACM V8 for new maintainers. It covers the end-to-end data flow, the role of every module, configuration surfaces, and the reasoning behind each major decision so that a new engineer can operate, extend, and hand off the system confidently.


1) Mental Model (Top-Level Flow)

        +--------------+    +-----------------+    +----------------+    +--------------------+
        | Ingestion    |    | Feature Builder |    | Detector Heads |    | Fusion & Episodes  |
        | (CSV / SQL)  | -> | (fast_features) | -> | (PCA/MHAL/IF/GMM|
        | acm_main     |    |                 |    |  AR1/OMR/etc.)  |    |  (fuse)            |
        +--------------+    +-----------------+    +----------------+    +--------------------+
               |                       |                       |                      |
               v                       v                       v                      v
        +--------------+    +-----------------+    +----------------+    +--------------------+
        | Regimes      |    | Calibration     |    | Drift          |    | Outputs & SQL      |
        | (regimes)    |    | (z-scores, per- |    | (cusum)        |    | (OutputManager)    |
        +--------------+    | regime/adaptive)|    +----------------+    +--------------------+
                                               \                                        |
                                                \-> Forecast/RUL (forecasting, rul_*) <-/

2) Runtime Modes & Entry Points

CLI: python -m core.acm_main --equip <EQUIP> [--train-csv ... --score-csv ...] [--config ...] [--clear-cache] [--log-level ...] [--disable-sql-logging]

SQL batch automation: python scripts/sql_batch_runner.py --equip FD_FAN [--resume --max-workers N --tick-minutes 240]
Uses SQL historian tables and calls usp_ACM_StartRun/usp_ACM_FinalizeRun. Handles cold-start retries and progress tracking (.sql_batch_progress.json).

File mode helper: powershell ./scripts/run/run_file_mode.ps1 (wraps acm_main with CSV defaults).

Mode decision:


3) Configuration Surfaces

Primary table (configs/config_table.csv or SQL ACM_Config)

Key paths (ParamPath) and reasoning:

SQL connection

CLI overrides


4) Module-by-Module Map

Orchestrator: core/acm_main.py

Feature Builder: core/fast_features.py

Detectors

Thresholding & Adaptation

Persistence & Metadata

I/O & SQL

Cold start & utilities

Episode culprits

Scripts (operations)


5) Data & Artifact Layout


6) How to Run ACM (End-to-End)

  1. Environment
  1. Config & data
  1. Run (file mode example)
python -m core.acm_main --equip FD_FAN ^
  --train-csv data/FD_FAN_BASELINE_DATA.csv ^
  --score-csv data/FD_FAN_BATCH_DATA.csv ^
  --log-level INFO
  1. Run (SQL mode example)
python -m core.acm_main --equip FD_FAN --log-level INFO
# Uses SQL config row, historian, and SQL sinks. Disable SQL log sink with --disable-sql-logging.
  1. Batch runner (SQL, continuous)
python scripts/sql_batch_runner.py --equip FD_FAN GAS_TURBINE --max-workers 2 --tick-minutes 240 --resume
  1. Outputs

7) Analytical Reasoning (Why each step exists)


8) Quick Reference: Functions by File


9) Onboarding Checklist


10) Troubleshooting Signals


11) Extend/Modify Safely


12) Minimal Config Examples

File mode row (config_table.csv)

EquipID,Category,ParamPath,ParamValue,ValueType
0,data,train_csv,data/FD_FAN_BASELINE_DATA.csv,string
0,data,score_csv,data/FD_FAN_BATCH_DATA.csv,string
0,data,timestamp_col,Timestamp,string
0,data,sampling_secs,60,int
0,features,window,16,int
0,models,pca.n_components,5,int
0,models,iforest.contamination,0.001,float
0,fusion,weights,"{""pca_spe_z"":0.25,""pca_t2_z"":0.25,""iforest_z"":0.2,""gmm_z"":0.15,""omr_z"":0.15}",json
0,output,dual_mode,false,bool

SQL mode row (config_table.csv)

EquipID,Category,ParamPath,ParamValue,ValueType
1,data,storage_backend,sql,string
1,data,timestamp_col,EntryDateTime,string
1,data,sampling_secs,60,int
1,models,pca.incremental,true,bool
1,runtime,reuse_model_fit,false,bool
1,output,dual_mode,true,bool

SQL connection (configs/sql_connection.ini)

[sqlserver]
driver=ODBC Driver 17 for SQL Server
server=YOUR_SQL_SERVER_HOST
database=ACM
uid=acm_user
pwd=***REDACTED***
trust_certificate=yes
timeout=30

13) Data & Timestamp Expectations


14) Detector & Fusion Defaults (quick reference)


15) Validation & Testing Recipes


16) Operational Signals & Runbook


17) Versioning & Change Control


18) Security & Secrets